{/* Copyright 2020 Adobe. All rights reserved.
This file is licensed to you under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License. You may obtain a copy
of the License at http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under
the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
OF ANY KIND, either express or implied. See the License for the specific language
governing permissions and limitations under the License. */}

import {Layout, VersionBadge} from '@react-spectrum/docs';
export default Layout;
import testUtilDocs from 'docs:@react-spectrum/test-utils';
import {ClassAPI, TypeLink} from '@react-spectrum/docs';

---
category: Concepts
---

# Testing

This page describes how to test an application built with React Spectrum, including how to
query the DOM tree for elements and simulate user interactions.

## Introduction

Running automated tests on your application helps ensure that it continues to work as expected over time.
You can use testing tools like [React Testing Library](https://testing-library.com/docs/react-testing-library/intro) along with test runners like
[Jest](https://jestjs.io) or [Mocha](https://mochajs.org) to test React Spectrum applications. These generally
work quite well out of the box but there are a few things to consider to ensure your tests are the best they
can be.

## Testing semantics

Many testing libraries expect you to query for elements in the DOM tree. For example, you might have a test
that renders a login page, finds the username and password fields, and simulates filling them out and
submitting the form.

Querying for these elements can be done in many ways. It's common to use CSS selectors for this,
but this can be problematic if you rely on implementation details of the component in these queries.
For example, if you query by a CSS class name that may change in a future update of React Spectrum, your
test will be brittle.

This also applies if you query for internal elements within a React Spectrum component. The DOM structure
that React Spectrum renders should be considered a black box, and it may change at any time, so you should
avoid relying on it.

The recommended way to query for React Spectrum components and their internals is by semantics. React Spectrum
components implement [ARIA patterns](https://www.w3.org/TR/wai-aria-practices-1.2/). ARIA is a W3C standard
that specifies the semantics for many UI components. This is used to expose them to assistive technology
such as screen readers, but can also be used in tests to operate the application programmatically. These semantics
are much less likely to change over time, and while other DOM nodes may be added or removed, and CSS classes
changed, the semantics are more likely to stay stable.

The main attribute to look for when querying is the [role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques).
This attribute represents the type of element a DOM node represents, e.g. a button, list option, or tab.
This is similar to the HTML element type (e.g. `<button>` or `<option>`), but since many React Spectrum
components are implemented with `<div>` for styling purposes, the `role` attribute is used instead to
communicate the element's semantics.

### React Testing Library

[React Testing Library](https://testing-library.com/docs/react-testing-library/intro) is useful because it
enforces that you write tests using semantics instead of implementation details. We use React Testing Library
to test React Spectrum itself, and it's quite easy to [query](https://testing-library.com/docs/dom-testing-library/api-queries)
elements by role, text, label, etc.

```tsx
import {render} from '@testing-library/react';

let tree = render(<MyComponent />);
let option = tree.getByRole('button');
```

## Test ids

Querying by semantics covers many scenarios, but what if you have many buttons on a page? How do you find the specific button
you're looking for in a test? In many cases this could be done by querying by the text in the button or an
accessibility label associated with it, but sometimes this might change over time or may be affected by things like
translations in different languages. In these cases, you may need a way to identify specific elements in tests, and that's
where test ids come in.

React Spectrum components pass all [data attributes](https://developer.mozilla.org/en-US/docs/Learn/HTML/Howto/Use_data_attributes)
through to their underlying DOM nodes, which allows you to use an attribute like `data-testid` to identify
a particular instance of a component. For example, you could add test ids to the two input elements
in a login form and use them to find the username and password fields.

This example uses React Testing Library, but the idea could be applied in a similar way with other
testing libraries.

```tsx
import {render} from '@testing-library/react';
import {TextField} from '@react-spectrum/textfield';

function LoginForm() {
  return (
    <>
      <TextField label="Username" data-testid="username" />
      <TextField label="Password" data-testid="password" />
    </>
  );
}

let tree = render(<LoginForm />);
let username = tree.getByTestId('username');
let password = tree.getByTestId('password');
```

## Triggering events

Most testing libraries include a way to simulate events on an element. React Spectrum components rely on
many different browser events to support different devices and platforms, so it's important to simulate
these correctly in your tests. For example, rather than only simulating a click event, the tests should
simulate all of the events that would occur if a real user were interacting with the component.

For example, a click is really a `mousemove` and `mouseover` the target, followed
by `mousedown`, `focus`, and `mouseup` events, and finally a `click` event. If you only simulated the `click`
event, you would be missing all of these other preceding events that occur in real-world situations and this
may make your test not work correctly. The implementation of the component may also change in the future to
expect these events, making your test brittle. In addition, browsers have default behavior that occurs on
certain events which would be missing, like focusing elements on mouse down, and toggling checkboxes on click.

The best way to handle this is with the [user-event](https://github.com/testing-library/user-event) library.
This lets you trigger high level interactions like a user would, and the library handles firing all of the individual
events that make up that interaction. If you use this library rather than firing events manually, your tests
will simulate real-world behavior much better and work as expected.

user-event can handle many types of interactions, e.g. clicks, tabbing, typing, etc. This example shows how you could
use it to render a login form and enter text in each field and click the submit button, just as a real user would.

```tsx
import {render} from '@testing-library/react';
import userEvent from '@testing-library/user-event';

let tree = render(<LoginForm />);

// Click on the username field to focus it, and enter the value.
userEvent.click(tree.getByLabelText('Username'));
userEvent.type(document.activeElement, 'devon');

// Tab to the password field, and enter the value.
userEvent.tab();
userEvent.type(document.activeElement, 'Pas$w0rd');

// Tab to the submit button and click it.
userEvent.tab();
userEvent.click(document.activeElement);
```

## Test setup and common gotchas

### Providers

When testing anything that uses a React Spectrum component, you must provide a wrapping Provider at the top level. Components rely on this wrapping provider
to inform them of the app's theme, locale, breakpoints and more. See the [Provider page](./Provider.html#application-provider) for a list of properties
your Provider can accept. If you see the following errors, you should check to see if you have a wrapping Provider.

```
Error: Uncaught [TypeError: Cannot destructure property 'scale' of '(0 , _provider.useProvider)(...)' as it is null.]
```

```
TypeError: Cannot read properties of null (reading 'scale')
```

If you are using React Testing Library, you can overwrite the provided `render` function so that it automatically includes a Provider by default.
Note the below example allows you to rerender the component with new Provider props but you'll need to requery any element you are asserting against
to get its updated state (e.g. `button = getByRole('button)`).

```tsx
import {RenderOptions as BaseRenderOptions, render} from '@testing-library/react';
import {Provider, defaultTheme} from '@adobe/react-spectrum';
import React, {ReactElement} from 'react';

// export everything from React Testing Library
export * from '@testing-library/react';

function ProviderWrapper(props) {
  let {children, ...providerProps} = props;
  return (
    <Provider theme={defaultTheme} scale="medium" {...providerProps}>
      {props.children}
    </Provider>
  );
}

interface RenderOptions extends BaseRenderOptions {
  providerProps: Omit<ProviderProps, 'children'>
}

function customRender(ui: ReactElement, options?: RenderOptions) {
  let rendered = render(ui, {wrapper: (props) => <ProviderWrapper {...props} {...options?.providerProps} />, ...options});
  return {
    ...rendered,
    rerender: (ui, options) => providerWrapperRender(ui, {container: rendered.container, ...options})
  };
}

// override render method
export {customRender as render};
```

### Timers

If you are using fake timers in your test suite, be aware that you may need to advance your timers whenever an animation or load is taking place.
Historically, this most commonly happened when a modals, popovers, or trays is opened or closed as a result of a simulated user action (e.g. opening a Picker's dropdown via click).
Additionally, we have `requestAnimationFrame` calls in various areas that you will need to also handle by advancing your timers in the tests. This happens most prominently
in our virtualized components due to the internals of our Virtualizer. In Jest, this can be handled by calling `act(() => jest.runAllTimers());` but you may require more precise control
depending on the other time-sensitive behavior you are testing. Please see [Jest's timer docs](https://jestjs.io/docs/timer-mocks) or the equivalent docs of your test frameworks for more information on how to do so.
It is also a good idea to run all timers to completion after each test case to avoid any left over transitions or timeouts that a component may have setup during its lifecycle.

```tsx
afterEach(() => {
  act(() => jest.runAllTimers());
});
```

Consider adding a `act(() => jest.runAllTimers());` after your simulated user interaction if you run into a test failure that looks like the following:

```
TestingLibraryElementError: Unable to find an accessible element with the role "listbox"
```

If you are using real timers instead, you can await for popovers to appear or for a particular state of your app to be reached. If you are using React Testing Library, you can perform a `waitFor` query
to wait for a dialog to appear:

```tsx
await waitFor(() => {
  expect(getByRole('dialog')).toBeInTheDocument();
});
```

### Desktop vs Mobile

Components like ComboBox and Picker render a different experience on mobile versus desktop. If you need to test mobile vs desktop for you app or want to make sure the React Spectrum
components are rendered only against a specific experience, you'll need to mock the window screen width accordingly. We currently use a
[screen width of 700px](https://github.com/adobe/react-spectrum/blob/5e487532e3ca4714513fb6ab64f7a78d9d1ca281/packages/%40react-spectrum/utils/src/useIsMobileDevice.ts#L15-L23) as the breakpoint
between mobile and desktop, so you should mock the `width` getter of `window.screen` to a value greater or less than this value accordingly. You may use <TypeLink links={testUtilDocs.links} type={testUtilDocs.exports.simulateMobile} /> and
<TypeLink links={testUtilDocs.links} type={testUtilDocs.exports.simulateDesktop} /> from the [@react-spectrum/test-utils](https://www.npmjs.com/package/@react-spectrum/test-utils) package to handle this width mocking for you in Jest:

The example below shows how you would set this up in Jest.

```tsx
import {simulateDesktop, simulateMobile} from '@react-spectrum/test-utils';

beforeAll(() => {
  simulateMobile();
});

afterAll(() => {
  jest.restoreAllMocks();
});
```

### Virtualized components

**Note:** As of [3.41](https://www.npmjs.com/package/@adobe/react-spectrum/v/3.41.0), Virtualizer behavior is disabled in tests automatically so the below mocks are now unnecessary for most test cases. However, if you are writing tests for interactions
that depend on item size calculations such as scroll into view, you will need to provide the mocks below as well as enable Virtualizer via the `VIRT_ON=1` process environment variable when running your tests.

Many of our collection components are virtualized out of the box and thus rely on DOM node measurement to know how large a item should be and how many items can be rendered at once.
To properly render virtualized components in a test environment, you'll have to to mock the `clientHeight` and `clientWidth` getters of the `HTMLElement` prototype.
`scrollHeight` and `scrollWidth` should also be mocked to set the height and width of each item. See below for an example implementation in Jest.

```tsx
beforeAll(function () {
  // The virtualizer will now think it has a visible area of 1000px x 1000px and that the items within it are 40px x 40px
  jest.spyOn(window.HTMLElement.prototype, 'clientWidth', 'get').mockImplementation(() => 1000);
  jest.spyOn(window.HTMLElement.prototype, 'clientHeight', 'get').mockImplementation(() => 1000);
  jest.spyOn(window.HTMLElement.prototype, 'scrollHeight', 'get').mockImplementation(() => 40);
  jest.spyOn(window.HTMLElement.prototype, 'scrollWidth', 'get').mockImplementation(() => 40);
});

afterAll(() => {
  jest.restoreAllMocks();
});
```

Please note that this is greatly simplified and still won't accurately reflect the behavior of the virtualizer in browser so we highly recommended that you avoid doing the above or use a browser based automated testing framework to
test virtualizer behavior. If you run into a test error where your collection component doesn't render any items/rows within it, try adding the above mocks.

### Simulating user long press

Components like ListView and TableView support long press to perform specific interactions like drag and drop or entering selection mode on mobile devices. Unfortunately, the approach of using the userEvent library to simulate a press event and running timers to hit the
long press internal timer threshold isn't sufficient due to `useLongPress`'s usage of `PointerEvent` and our own detection of `virtual` vs `mouse`/`touch` pointer types. Mock [PointerEvent](https://github.com/adobe/react-spectrum/blob/16ff0efac57eebeb1cd601ab376ce7c58a4e4efd/packages/dev/test-utils/src/events.ts#L70-L103)
globally and use `fireEvent` from `@testing-library/react` to properly simulate these long press events in your tests.
If you are using Jest, you can call our <TypeLink links={testUtilDocs.links} type={testUtilDocs.exports.installPointerEvent} /> utility to automatically set up and tear down this mock in your test.
Additionally, you are using fake timers and don't need to control the specific timings around the long press interaction, feel free to use our <TypeLink links={testUtilDocs.links} type={testUtilDocs.exports.triggerLongPress} /> utility as shown below.

```tsx
import {fireEvent} from '@testing-library/react';
import {installPointerEvent, triggerLongPress} from '@react-spectrum/test-utils';
installPointerEvent();

// In test case
let button = getByRole('button');

// With fireEvent and specific timing control
fireEvent.pointerDown(el, {pointerType: 'touch'});
act(() => jest.advanceTimersByTime(800));
fireEvent.up(el, {pointerType: 'touch'});

// With triggerLongPress
triggerLongPress(button);
```

### Simulating move event

Components like ColorArea, ColorSlider, ColorWheel, and Slider each feature a draggable handle that a user can interact with to change the component's value. Similar to long press, the interactions offered by userEvent library aren't sufficient to trigger
the underlying event handlers governing these drag/move operations. [Mock MouseEvent globally](https://github.com/adobe/react-spectrum/blob/16ff0efac57eebeb1cd601ab376ce7c58a4e4efd/packages/dev/test-utils/src/events.ts#L44-L68) and `fireEvent` from `@testing-library/react` to simulate these drag/move events in your tests.
If you are using Jest, you can call our <TypeLink links={testUtilDocs.links} type={testUtilDocs.exports.installMouseEvent} /> utility to automatically set up and tear down this mock in your test. Additionally, the track dimensions
for the draggable handle should be mocked so that the move operation calculations can be properly computed.

```tsx
import {fireEvent} from '@testing-library/react';
import {installMouseEvent} from '@react-spectrum/test-utils';
installMouseEvent();

beforeAll(() => {
  jest.spyOn(window.HTMLElement.prototype, 'getBoundingClientRect').mockImplementation(() => ({top: 0, left: 0, width: 100, height: 10}));
})

// In test case
let sliderThumb = getByRole('slider').parentElement;

// With fireEvent, move thumb from 0 to 50
fireEvent.mouseDown(thumb, {clientX: 0, pageX: 0});
fireEvent.mouseMove(thumb, {pageX: 50});
fireEvent.mouseUp(thumb, {pageX: 50});
```

## Snapshot tests

If you are using React 16 or 17, you may run into an issue where the ids generated by the React Spectrum components are changing on every snapshot. To remedy this, simply wrap your component in a [SSRProvider](react-aria:SSRProvider).
Note that you can use the SSRProvider even if your component doesn't support server side rendering, it will simply stabilize the ids generated.

```tsx
import {SSRProvider, Provider, lightTheme} from '@adobe/react-spectrum';

<SSRProvider>
  <Provider theme={lightTheme}>
    <YourApp />
  </Provider>
</SSRProvider>
```

## React Spectrum test utils <VersionBadge version="beta" style={{marginLeft: 4, verticalAlign: 'bottom'}} />

In addition to the test utilities mentioned above, [@react-spectrum/test-utils](https://www.npmjs.com/package/@react-spectrum/test-utils) re-exports the same test utils available in `@react-aria/test-utils`, including
the ARIA pattern testers. These testers are set of testing utilities that aims to make writing unit tests easier for consumers of React Spectrum. By using the ARIA specification for any given component pattern as a source of truth,
we can make assumptions about the existence of various aria attributes in a component. This allows us to navigate the component's DOM structure, simulate common interactions, and verify the resulting state of the component.

### Installation

`@react-spectrum/test-utils` can be installed using a package manager like [npm](https://docs.npmjs.com/cli/npm) or [yarn](https://classic.yarnpkg.com/lang/en/).

```
yarn add --dev @react-spectrum/test-utils
```

Please note that this library uses [@testing-library/react@16](https://www.npmjs.com/package/@testing-library/react) and [@testing-library/user-event@14](https://www.npmjs.com/package/@testing-library/user-event). This means that you need
to be on React 18+ in order for these utilities to work.

### Setup

Once installed, you can access the `User` that `@react-spectrum/test-utils` provides in your test file as shown below. This user only needs to be initialized once and then can be used to generate
specific ARIA pattern tester in your test cases. This gives you access to that pattern's specific utilities that you can then call within your test to query for specific subcomponents or simulate common interactions.
See [below](#patterns) for what patterns are currently supported.

```ts
// YourTest.test.ts
import {screen} from '@testing-library/react';
import {User} from '@react-spectrum/test-utils';

// Provide whatever method of advancing timers you use in your test, this example assumes Jest with fake timers.
// 'interactionType' specifies what mode of interaction should be simulated by the tester
// 'advanceTimer' is used by the tester to advance the timers in the tests for specific interactions (e.g. long press)
let testUtilUser = new User({interactionType: 'mouse', advanceTimer: jest.advanceTimersByTime});
// ...

it('my test case', async function () {
  // Render your test component/app
  render();
  // Initialize the table tester via providing the 'Table' pattern name and the root element of said table
  let table = testUtilUser.createTester('Table', {root: screen.getByTestId('test_table')});

  // ...
});
```

See below for the full definition of the `User` object.

<ClassAPI links={testUtilDocs.links} class={testUtilDocs.exports.User} />

### Patterns

Below is a list of the ARIA patterns testers currently supported by `createTester`. See the accompanying component testing docs pages for a sample of how to use
the testers in your test suite.

-  [ComboBox](ComboBox.html#test-utils)

-  [ListView](ListView.html#test-utils)

-  [ListBox](ListBox.html#test-utils)

-  [MenuTrigger](MenuTrigger.html#test-utils)

-  [Picker](Picker.html#test-utils)

-  [TableView](TableView.html#test-utils)

-  [Tabs](Tabs.html#test-utils)

-  [TreeView](TreeView.html#test-utils)
